<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Accessing Enterprise Beans - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level3"><a href="gipmb.html">What Is an Enterprise Bean?</a></p>
<p class="toc level4"><a href="gipmb.html#giplk">Benefits of Enterprise Beans</a></p>
<p class="toc level4"><a href="gipmb.html#gipkn">When to Use Enterprise Beans</a></p>
<p class="toc level4"><a href="gipmb.html#gipnm">Types of Enterprise Beans</a></p>
<p class="toc level3 tocsp"><a href="gipjg.html">What Is a Session Bean?</a></p>
<p class="toc level4"><a href="gipjg.html#gipkr">Types of Session Beans</a></p>
<p class="toc level5"><a href="gipjg.html#gipnl">Stateful Session Beans</a></p>
<p class="toc level5"><a href="gipjg.html#gipin">Stateless Session Beans</a></p>
<p class="toc level5"><a href="gipjg.html#gipim">Singleton Session Beans</a></p>
<p class="toc level4 tocsp"><a href="gipjg.html#gipmt">When to Use Session Beans</a></p>
<p class="toc level3 tocsp"><a href="gipko.html">What Is a Message-Driven Bean?</a></p>
<p class="toc level4"><a href="gipko.html#gipmj">What Makes Message-Driven Beans Different from Session Beans?</a></p>
<p class="toc level4"><a href="gipko.html#gipjx">When to Use Message-Driven Beans</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3 tocsp"><a href="">Accessing Enterprise Beans</a></p>
<p class="toc level4"><a href="#girfl">Using Enterprise Beans in Clients</a></p>
<p class="toc level5"><a href="#girgn">Portable JNDI Syntax</a></p>
<p class="toc level4 tocsp"><a href="#gipiz">Deciding on Remote or Local Access</a></p>
<p class="toc level4"><a href="#gipmz">Local Clients</a></p>
<p class="toc level5"><a href="#gipsc">Accessing Local Enterprise Beans Using the No-Interface View</a></p>
<p class="toc level5"><a href="#gipse">Accessing Local Enterprise Beans That Implement Business Interfaces</a></p>
<p class="toc level4 tocsp"><a href="#gipiu">Remote Clients</a></p>
<p class="toc level4"><a href="#gipkd">Web Service Clients</a></p>
<p class="toc level4"><a href="#giply">Method Parameters and Access</a></p>
<p class="toc level5"><a href="#giplx">Isolation</a></p>
<p class="toc level5"><a href="#gipkv">Granularity of Accessed Data</a></p>
</div>
<p class="toc level3 tocsp"><a href="gipio.html">The Contents of an Enterprise Bean</a></p>
<p class="toc level4"><a href="gipio.html#gipnz">Packaging Enterprise Beans in EJB JAR Modules</a></p>
<p class="toc level4"><a href="gipio.html#gippi">Packaging Enterprise Beans in WAR Modules</a></p>
<p class="toc level3 tocsp"><a href="gipks.html">Naming Conventions for Enterprise Beans</a></p>
<p class="toc level3"><a href="giplj.html">The Lifecycles of Enterprise Beans</a></p>
<p class="toc level4"><a href="giplj.html#gipln">The Lifecycle of a Stateful Session Bean</a></p>
<p class="toc level4"><a href="giplj.html#giplm">The Lifecycle of a Stateless Session Bean</a></p>
<p class="toc level4"><a href="giplj.html#giprx">The Lifecycle of a Singleton Session Bean</a></p>
<p class="toc level4"><a href="giplj.html#gipkw">The Lifecycle of a Message-Driven Bean</a></p>
<p class="toc level3 tocsp"><a href="giplg.html">Further Information about Enterprise Beans</a></p>
<p class="toc level2 tocsp"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="gipko.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="gipio.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="gipjf"></a><h2>Accessing Enterprise Beans</h2>
<a name="indexterm-1349"></a>
<hr><p><b>Note - </b>The material in this section applies only to session beans and not to
message-driven beans. Because they have a different programming model, message-driven beans do not
have interfaces or no-interface views that define client access.</p>


<hr>
<p><a name="indexterm-1350"></a><a name="indexterm-1351"></a>Clients access enterprise beans either through a <b>no-interface view</b> or through a <b>business interface</b>. A
no-interface view of an enterprise bean exposes the public methods of the enterprise
bean implementation class to clients. Clients using the no-interface view of an enterprise
bean may invoke any public methods in the enterprise bean implementation class or
any superclasses of the implementation class. A business interface is a standard Java
programming language interface that contains the business methods of the enterprise bean.</p>

<p><a name="indexterm-1352"></a>A client can access a session bean only through the methods defined in
the bean&rsquo;s business interface or through the public methods of an enterprise bean
that has a no-interface view. The business interface or no-interface view defines the
client&rsquo;s view of an enterprise bean. All other aspects of the enterprise bean
(method implementations and deployment settings) are hidden from the client.</p>

<p>Well-designed interfaces and no-interface views simplify the development and maintenance of Java EE
applications. Not only do clean interfaces and no-interface views shield the clients from
any complexities in the EJB tier, but they also allow the enterprise beans
to change internally without affecting the clients. For example, if you change the
implementation of a session bean business method, you won&rsquo;t have to alter the
client code. But if you were to change the method definitions in the
interfaces, you might have to modify the client code as well. Therefore, it
is important that you design the interfaces and no-interface views carefully to isolate
your clients from possible changes in the enterprise beans.</p>

<p>Session beans can have more than one business interface. Session beans should, but
are not required to, implement their business interface or interfaces.</p>



<a name="girfl"></a><h3>Using Enterprise Beans in Clients</h3>
<p><a name="indexterm-1353"></a><a name="indexterm-1354"></a><a name="indexterm-1355"></a>The client of an enterprise bean obtains a reference to an instance of
an enterprise bean through either <b>dependency injection</b>, using Java programming language annotations, or <b>JNDI lookup</b>, using
the Java Naming and Directory Interface syntax to find the enterprise bean instance.</p>

<p>Dependency injection is the simplest way of obtaining an enterprise bean reference. Clients
that run within a Java EE server-managed environment, JavaServer Faces web applications, JAX-RS
web services, other enterprise beans, or Java EE application clients, support dependency injection
using the <tt>javax.ejb.EJB</tt> annotation.</p>

<p>Applications that run outside a Java EE server-managed environment, such as Java SE
applications, must perform an explicit lookup. JNDI supports a global syntax for identifying
Java EE components to simplify this explicit lookup.</p>



<a name="girgn"></a><h4>Portable JNDI Syntax</h4>
<p>Three JNDI namespaces are used for portable JNDI lookups: <tt>java:global</tt>, <tt>java:module</tt>, and
<tt>java:app</tt>.</p>


<ul><li><p>The <tt>java:global</tt> JNDI namespace is the portable way of finding remote enterprise beans using JNDI lookups. JNDI addresses are of the following form:</p>

<pre>java:global[/<i>application name</i>]/<i>module name</i>/<i>enterprise bean name</i>[/<i>interface name</i>]</pre><p>Application name and module name default to the name of the application and module minus the file extension. Application names are required only if the application is packaged within an EAR. The interface name is required only if the enterprise bean implements more than one business interface.</p>

</li>
<li><p>The <tt>java:module</tt> namespace is used to look up local enterprise beans within the same module. JNDI addresses using the <tt>java:module</tt> namespace are of the following form:</p>

<pre>java:module/<i>enterprise bean name</i>/[<i>interface name</i>]</pre><p>The interface name is required only if the enterprise bean implements more than one business interface.</p>

</li>
<li><p>The <tt>java:app</tt> namespace is used to look up local enterprise beans packaged within the same application. That is, the enterprise bean is packaged within an EAR file containing multiple Java EE modules. JNDI addresses using the <tt>java:app</tt> namespace are of the following form:</p>

<pre>java:app[/<i>module name</i>]/<i>enterprise bean name</i>[/<i>interface name</i>]</pre><p>The module name is optional. The interface name is required only if the enterprise bean implements more than one business interface.</p>

</li></ul>
<p>For example, if an enterprise bean, <tt>MyBean</tt>, is packaged within the web application
archive <tt>myApp.war</tt>, the module name is <tt>myApp</tt>. The portable JNDI name is <tt>java:module/MyBean</tt>
An equivalent JNDI name using the <tt>java:global</tt> namespace is <tt>java:global/myApp/MyBean</tt>.</p>



<a name="gipiz"></a><h3>Deciding on Remote or Local Access</h3>
<p>When you design a Java EE application, one of the first decisions
you make is the type of client access allowed by the enterprise beans:
remote, local, or web service.</p>

<p>Whether to allow local or remote access depends on the following factors.</p>


<ul><li><p><b>Tight or loose coupling of related beans</b>: Tightly coupled beans depend on one another. For example, if a session bean that processes sales orders calls a session bean that emails a confirmation message to the customer, these beans are tightly coupled. Tightly coupled beans are good candidates for local access. Because they fit together as a logical unit, they typically call each other often and would benefit from the increased performance that is possible with local access.</p>

</li>
<li><p><b>Type of client</b>: If an enterprise bean is accessed by application clients, it should allow remote access. In a production environment, these clients almost always run on machines other than those on which the GlassFish Server is running. If an enterprise bean&rsquo;s clients are web components or other enterprise beans, the type of access depends on how you want to distribute your components.</p>

</li>
<li><p><a name="indexterm-1356"></a><b>Component distribution</b>: Java EE applications are scalable because their server-side components can be distributed across multiple machines. In a distributed application, for example, the server that the web components run on may not be the one on which the enterprise beans they access are deployed. In this distributed scenario, the enterprise beans should allow remote access.</p>

</li>
<li><p><a name="indexterm-1357"></a><b>Performance</b>: Owing to such factors as network latency, remote calls may be slower than local calls. On the other hand, if you distribute components among different servers, you may improve the application&rsquo;s overall performance. Both of these statements are generalizations; performance can vary in different operational environments. Nevertheless, you should keep in mind how your application design might affect performance.</p>

</li></ul>
<p>If you aren&rsquo;t sure which type of access an enterprise bean should have,
choose remote access. This decision gives you more flexibility. In the future, you
can distribute your components to accommodate the growing demands on your application.</p>

<p><a name="indexterm-1358"></a><a name="indexterm-1359"></a>Although it is uncommon, it is possible for an enterprise bean to allow
both remote and local access. If this is the case, either the
business interface of the bean must be explicitly designated as a business interface by
being decorated with the <tt>@Remote</tt> or <tt>@Local</tt> annotations, or the bean class must
explicitly designate the business interfaces by using the <tt>@Remote</tt> and <tt>@Local</tt> annotations. The same
business interface cannot be both a local and a remote business interface.</p>



<a name="gipmz"></a><h3>Local Clients</h3>
<a name="indexterm-1360"></a><p>A local client has these characteristics.</p>


<ul><li><p>It must run in the same application as the enterprise bean it accesses.</p>

</li>
<li><p>It can be a web component or another enterprise bean.</p>

</li>
<li><p>To the local client, the location of the enterprise bean it accesses is not transparent.</p>

</li></ul>
<p>The no-interface view of an enterprise bean is a local view. The
public methods of the enterprise bean implementation class are exposed to local clients that
access the no-interface view of the enterprise bean. Enterprise beans that use the
no-interface view do not implement a business interface.</p>

<p><a name="indexterm-1361"></a><a name="indexterm-1362"></a>The <b>local business interface</b> defines the bean&rsquo;s business and lifecycle methods. If the bean&rsquo;s business interface
is not decorated with <tt>@Local</tt> or <tt>@Remote</tt>, and if the bean class does
not specify the interface using <tt>@Local</tt> or <tt>@Remote</tt>, the business interface is
by default a local interface.</p>

<p>To build an enterprise bean that allows only local access, you may, but
are not required to, do one of the following:</p>


<ul><li><p>Create an enterprise bean implementation class that does not implement a business interface, indicating that the bean exposes a no-interface view to clients. For example:</p>

<pre>@Session
public class MyBean { ... }</pre></li>
<li><p>Annotate the business interface of the enterprise bean as a <tt>@Local</tt> interface. For example:</p>

<pre>@Local
public interface InterfaceName { ... }</pre></li>
<li><p>Specify the interface by decorating the bean class with <tt>@Local</tt> and specify the interface name. For example:</p>

<pre>@Local(<i>InterfaceName</i>.class)
public class <i>BeanName</i> implements <i>InterfaceName</i> { ... }</pre></li></ul>


<a name="gipsc"></a><h4>Accessing Local Enterprise Beans Using the No-Interface View</h4>
<p>Client access to an enterprise bean that exposes a local, no-interface view is
accomplished through either dependency injection or JNDI lookup.</p>


<ul><li><p>To obtain a reference to the no-interface view of an enterprise bean through dependency injection, use the <tt>javax.ejb.EJB</tt> annotation and specify the enterprise bean&rsquo;s implementation class:</p>

<pre>@EJB
ExampleBean exampleBean;</pre></li>
<li><p>To obtain a reference to the no-interface view of an enterprise bean through JNDI lookup, use the <tt>javax.naming.InitialContext</tt> interface&rsquo;s <tt>lookup</tt> method:</p>

<pre>ExampleBean exampleBean = (ExampleBean)
        InitialContext.lookup("java:module/ExampleBean");</pre></li></ul>
<p>Clients <b>do not</b> use the <tt>new</tt> operator to obtain a new instance of an
enterprise bean that uses a no-interface view.</p>



<a name="gipse"></a><h4>Accessing Local Enterprise Beans That Implement Business Interfaces</h4>
<p>Client access to enterprise beans that implement local business interfaces is accomplished through
either dependency injection or JNDI lookup.</p>


<ul><li><p>To obtain a reference to the local business interface of an enterprise bean through dependency injection, use the <tt>javax.ejb.EJB</tt> annotation and specify the enterprise bean&rsquo;s local business interface name:</p>

<pre>@EJB
Example example;</pre></li>
<li><p>To obtain a reference to a local business interface of an enterprise bean through JNDI lookup, use the <tt>javax.naming.InitialContext</tt> interface&rsquo;s <tt>lookup</tt> method:</p>

<pre>ExampleLocal example = (ExampleLocal)
         InitialContext.lookup("java:module/ExampleLocal");</pre></li></ul>


<a name="gipiu"></a><h3>Remote Clients</h3>
<a name="indexterm-1363"></a><p>A remote client of an enterprise bean has the following traits.</p>


<ul><li><p>It can run on a different machine and a different JVM from the enterprise bean it accesses. (It is not required to run on a different JVM.)</p>

</li>
<li><p>It can be a web component, an application client, or another enterprise bean.</p>

</li>
<li><p>To a remote client, the location of the enterprise bean is transparent.</p>

</li>
<li><p>The enterprise bean must implement a business interface. That is, remote clients <b>may not</b> access an enterprise bean through a no-interface view.</p>

</li></ul>
<p>To create an enterprise bean that allows remote access, you must either</p>


<ul><li><p>Decorate the business interface of the enterprise bean with the <tt>@Remote</tt> annotation:</p>

<pre>@Remote
public interface InterfaceName { ... }</pre></li>
<li><p>Decorate the bean class with <tt>@Remote</tt>, specifying the business interface or interfaces:</p>

<pre>@Remote(InterfaceName.class)
public class BeanName implements InterfaceName { ... }</pre></li></ul>
<p><a name="indexterm-1364"></a><a name="indexterm-1365"></a><a name="indexterm-1366"></a>The <b>remote interface</b> defines the business and lifecycle methods that are specific to the
bean. For example, the remote interface of a bean named <tt>BankAccountBean</tt> might have business
methods named <tt>deposit</tt> and <tt>credit</tt>. <a href="#gipno">Figure&nbsp;22-1</a> shows how the interface controls the client&rsquo;s
view of an enterprise bean.</p>

<a name="gipno"></a><p class="caption">Figure&nbsp;22-1 Interfaces for an Enterprise Bean with Remote Access</p><img src="figures/ejbcon-enterpriseBeanInterfaces.gif" alt="Diagram showing a remote client accessing an enterprise bean's methods through its remote interface."></img><p>Client access to an enterprise bean that implements a remote business interface is
accomplished through either dependency injection or JNDI lookup.</p>


<ul><li><p>To obtain a reference to the remote business interface of an enterprise bean through dependency injection, use the <tt>javax.ejb.EJB</tt> annotation and specify the enterprise bean&rsquo;s remote business interface name:</p>

<pre>@EJB
Example example;</pre></li>
<li><p>To obtain a reference to a remote business interface of an enterprise bean through JNDI lookup, use the <tt>javax.naming.InitialContext</tt> interface&rsquo;s <tt>lookup</tt> method:</p>

<pre>ExampleRemote example = (ExampleRemote)
        InitialContext.lookup("java:global/myApp/ExampleRemote");</pre></li></ul>


<a name="gipkd"></a><h3>Web Service Clients</h3>
<a name="indexterm-1367"></a><p>A web service client can access a Java EE application in two
ways. First, the client can access a web service created with JAX-WS. (For
more information on JAX-WS, see <a href="bnayl.html">Chapter&nbsp;18, Building Web Services with JAX-WS</a>.) Second, a web service client can invoke
the business methods of a stateless session bean. Message beans cannot be accessed
by web service clients.</p>

<p>Provided that it uses the correct protocols (SOAP, HTTP, WSDL), any web service
client can access a stateless session bean, whether or not the client is
written in the Java programming language. The client doesn&rsquo;t even &ldquo;know&rdquo; what technology
implements the service: stateless session bean, JAX-WS, or some other technology. In addition,
enterprise beans and web components can be clients of web services. This flexibility
enables you to integrate Java EE applications with web services.</p>

<p><a name="indexterm-1368"></a>A web service client accesses a stateless session bean through the bean&rsquo;s web
service endpoint implementation class. By default, all public methods in the bean class
are accessible to web service clients. The <tt>@WebMethod</tt> annotation may be used
to customize the behavior of web service methods. If the <tt>@WebMethod</tt> annotation is
used to decorate the bean class&rsquo;s methods, only those methods decorated with <tt>@WebMethod</tt>
are exposed to web service clients.</p>

<p>For a code sample, see <a href="bnbor.html">A Web Service Example: <tt>helloservice</tt></a>.</p>



<a name="giply"></a><h3>Method Parameters and Access</h3>
<p>The type of access affects the parameters of the bean methods that
are called by clients. The following sections apply not only to method parameters but
also to method return values.</p>



<a name="giplx"></a><h4>Isolation</h4>
<p>The parameters of remote calls are more isolated than those of local calls.
With remote calls, the client and the bean operate on different copies of
a parameter object. If the client changes the value of the object,
the value of the copy in the bean does not change. This layer
of isolation can help protect the bean if the client accidentally modifies the
data.</p>

<p>In a local call, both the client and the bean can modify
the same parameter object. In general, you should not rely on this side
effect of local calls. Perhaps someday you will want to distribute your components,
replacing the local calls with remote ones.</p>

<p>As with remote clients, web service clients operate on different copies of parameters
than does the bean that implements the web service.</p>



<a name="gipkv"></a><h4>Granularity of Accessed Data</h4>
<p>Because remote calls are likely to be slower than local calls, the
parameters in remote methods should be relatively coarse-grained. A coarse-grained object contains more data
than a fine-grained one, so fewer access calls are required. For the same
reason, the parameters of the methods called by web service clients should also
be coarse-grained.</p>


         </div>
         <div class="navigation">
             <a href="gipko.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="gipio.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

